% PERSPECTIVE TRANSFORMATION
% ==========================
%
% This source file illustrates the perspective transformation combined with
% image convolution. The outlined functionality can be achieved by using
% matlab's inbuilt functions, but that is not helpful for implementation
% in other programming environment. Therefore this example shows step-by-step
% approach using matlab's basic functions. 
%
% First step is the calculation of the transformation matrix:
%
% Define the corner points around the area you want to transform into rectangle
% The corners of the trapezoid used in the example are:
%
%     [-100,1]      [1100,1]
%        x              x
%
%
%          x         x
%       [1,1450] [1000,1450] 
%
% The transformation matrix is a classic 3x3 matrix known from all other point
% operations. The matrix has 9 elements. The 4 points are used in the equations 
% for calculating the x,y coordinates from u,v plane. That delivers 8 equations. 
% The ninth element in the transformation matrix - a33 is considered 1, while 
% that parameter is responsible for overall scale only.
%
% The equations are determined from the classic transformations:
%
%                          | a11 a12 a13 |
%     [x',y',w'] = [u,v,w] | a21 a22 a23 |
%                          | a31 a32 a33 |
%
% where the relationship x = x'/w' and y = y'/w'.
%
% The corresponding calculation:
%
%         x'     a11u + a21v + a31
%    x = ---- = -------------------
%         w'     a13u + a23v + a33
%
%         y'     a12u + a22v + a32
%    y = ---- = -------------------
%         w'     a13u + a23v + a33
%
% unlike the affine transformation the variable w' is not constant and may take different values
% for different u,v combinations. Therefore we need to consider it in the calculations.
%
% The equations can be expressed as:
%
%    x = a11u + a21v + a31 - a13ux - a23vx
%    y = a12u + a22v + a32 - a13uy - a23vy
%
% This equations are taken for 4 corner points of the enveloping trapezoid and the system 8x8
% emerges:
%
%    | u0  v0  1  0  0  0 -u0x0 -v0x0 |   | a11 |   | x0 |
%    | u1  v1  1  0  0  0 -u1x1 -v1x1 |   | a21 |   | x1 |
%    | u2  v2  1  0  0  0 -u2x2 -v2x2 |   | a31 |   | x2 |
%    | u3  v3  1  0  0  0 -u3x3 -v3x3 |   | a12 |   | x3 |
%    |  0   0  0 u0 v0  1 -u0y0 -v0y0 | . | a22 | = | y0 |
%    |  0   0  0 u1 v1  1 -u1y1 -v1y1 |   | a32 |   | y1 |
%    |  0   0  0 u2 v2  1 -u2y2 -v2y2 |   | a13 |   | y2 |
%    |  0   0  0 u3 v3  1 -u3y3 -v3y3 |   | a23 |   | y3 |
%
% which is a classic example for matrix based solution. Use premultiplication with inverse
% matrix A, which yields identity matrix on left side. By calculating the right side we get
% the desired result:
%
%    M.a=x
%    inv(M).M.a=inv(M).x
%    a=inv(M).x
%
% The result will deliver the coefficients a in a form of column vector, where the elements are
% arranged like this:
%
%  | a11 |
%  | a21 |
%  | a31 |
%  | a12 |
%  | a22 |
%  | a32 |
%  | a13 |
%  | a23 |
%
% ,which we rearrange into the transformation matrix:
%
%                          | a11 a12 a13 |
%     [x',y',w'] = [u,v,w] | a21 a22 a23 |
%                          | a31 a32 a33 |
%
%   NOTE: this example uses 'postmultiplication' syntax. It is equivalent to 'premultiplication'
%   syntax, which is frequently found in literature. The transformation matrix must be
%   transposed in order to swap for premultiplication syntax. 
%

% ============================ DATA for TEST IMAGE : SAMPLE.SMALL.TRIM.JPG ==========================================
% This approach shows optimized work with trimmed image. The image is cropped to smallest
% possible selection. The selection takes the longest horizontal edge and trims the image for
% it. The vertical edges are supposed to have identical length. It is the initial simplification
% I use in this example. The transformation takes the x-coordinate only, y-coordinate is not
% modified. 

% -------------------------------------------------------------------------------------------------------------------
% IMAGE: sample.small.trim.jpg
%x=[-21;444;426;1]; % This is the stretching the trapezoid to fill the rectangle, x-points only 
%y=[1;1;559;559]; %  y-points of the stretching trapezoid. They are identical with the image size 
% -------------------------------------------------------------------------------------------------------------------

% -------------------------------------------------------------------------------------------------------------------
% IMAGE: big.issue.trim.jpg
%x=[-297;266+2074;2074;1]; % This is the stretching the trapezoid to fill the rectangle, x-points only 
%y=[1;1;2345;2345]; %  y-points of the stretching trapezoid. They are identical with the image size 
% -------------------------------------------------------------------------------------------------------------------
%
% -------------------------------------------------------------------------------------------------------------------
% IMAGE: small.big.issue.trim.jpg
x=[-115;903;800;1]; % This is the stretching the trapezoid to fill the rectangle, x-points only 
y=[1;1;905;905]; %  y-points of the stretching trapezoid. They are identical with the image size 
% -------------------------------------------------------------------------------------------------------------------

